﻿//--------------------------------------------------------------------------
// 
//  Copyright (c) Chili Software.  All rights reserved. 
// 
//  File: PersisDepths.cs
//
//  Description: Specifies persist depth of loaded persistent graph.
// 
//--------------------------------------------------------------------------

using System;

namespace Chili.Opf3
{
	/// <summary>
	/// Allows to specify the depth of the <strong>loaded object graph</strong> that is
	/// persisted during the save process.
	/// </summary>
	/// <remarks>
	/// This enumeration is used in the
	/// <see cref="ObjectContext.PersistChanges{T}(T, PersistDepths)">PersistChanges</see>
	/// method of the <see cref="ObjectContext">ObjectContext</see> and allows to specify
	/// which part of the loaded object graph is persisted. It's important to know
	/// that this enumeration <strong>applies only to loaded related objects and
	/// collections</strong> (See
	/// <see cref="Opf3.Relations.ObjectHolder{T}">ObjectHolder</see>,
	/// <see cref="Opf3.Relations.ObjectSetHolder{T}">ObjectSetHolder</see> and
	/// <see cref="Opf3.Relations.ObjectListHolder{T}">ObjectListHolder</see> for further
	/// information about delayed loading of related objects). This means that not loaded
	/// related collections and objects are excluded by design.
	/// </remarks>
	/// <example>
	///     The following example shows you how to use the enumeration while saving persistent
	///     objects. 
	///     <code lang="CS">
	/// // Create a storage and the context.
	/// OleDbStorage storage = new OleDbStorage("connectionstring ...");
	/// ObjectContext context = new ObjectContext(storage);
	///  
	/// // Load the user with the Id '1'.
	/// User user = context.GetObject&lt;User&gt;("Id = {0}", "1");
	/// if (user != null)
	/// {
	///     // Get the calls of the user. The calls are only loaded
	///     // during the first request of the property (delayed loading).
	///     ObjectSet&lt;Call&gt; calls = user.Calls;
	/// }
	///  
	/// // Save the user object. Since flat is used only the object
	/// // without the calls is saved.
	/// context.PersistChanges(user, PersistDepth.Flat);
	///  
	/// // Save the user object. Using FirstLevel means that the object
	/// // itself plus the calls are saved. If each call would contain
	/// // another connected object or collection that wouldn't be saved.
	/// context.PersistChanges(user, PersistDepth.FirstLevel);
	///     </code>
	/// </example>
	[Serializable]
	public enum PersistDepths
	{
		/// <summary>
		/// No persist depth is specified.
		/// </summary>
		None,
		/// <summary>
		/// When using this option only the object itself is persisted. 
		/// Connected object collections or connected objects aren't persisted.
		/// </summary>
		Flat,
		/// <summary>
		/// The first level of connected objects is persisted. This means that the object
		/// itself plus the first level of loaded connected objects and collections are persisted.
		/// If those objects contain other connected objects they aren't persisted.
		/// </summary>
		FirstLevel,
		/// <summary>
		/// The whole object graph is persited. All loaded connected objects
		/// in any level are persisted.
		/// </summary>
		FullObjectGraph
	}
}
